For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
Install
Docs Home
/
Tools
/
SQL Interface
/
Install
Docs Home
/
Tools
/
SQL Interface
/
Install

Connect Your SQL Tool to MongoDB

Connect your SQL tool, such as Tableau, Power BI, or DBeaver to your MongoDB Atlas or Enterprise Advanced (EA) database.

All three SQL Interface deployment options use the same JDBC and ODBC drivers, so the steps on this page are the same whether you connect to an Atlas dedicated cluster, an Atlas federated database instance, or a self-managed Enterprise Advanced (EA) deployment. Configure your deployment to accept SQL connections first. To learn how, see SQL Interface Server Setup.

Note

MongoDB officially supports Tableau (Desktop, Server, or Cloud) and Power BI Desktop (Desktop and Service) with its JDBC and ODBC drivers. You can use the JDBC and ODBC drivers with other SQL-92 compatible tools, but MongoDB cannot guarantee compatibility. Test your specific SQL Interface features to confirm support.

Connect Tableau

Connect an Atlas dedicated cluster, an Atlas federated database instance, or a self-hosted Enterprise Advanced (EA) database to Tableau (Desktop or Server) using the Tableau Connector for MongoDB.

Prerequisites

Procedure

The following steps show you how to connect to MongoDB with Tableau:

1

Download the Tableau Connector for MongoDB.

Note

Tableau Desktop and Tableau Server version 2025 and later bundle the Tableau Connector for MongoDB. If your version of Tableau already includes the connector, skip this step. To use a different version than the one bundled with Tableau, complete this step.

For Tableau Desktop, you can also install the connector from Tableau. Search the Tableau Exchange for MongoDB SQL interface by MongoDB, then click Install and restart Tableau.

  1. Download the latest Tableau Connector taco file from the MongoDB download center.

  2. Move the taco file into the appropriate directory for your operating system:

    • Windows: C:\Users\<user>\Documents\My Tableau Repository\Connectors

    • MacOS: ~/Documents/My Tableau Repository/Connectors

    • Linux: /opt/tableau/connectors

Important

If you download a new version of the Tableau Connector for MongoDB, delete the previous taco file from your Connectors directory to ensure that Tableau uses the latest version.

2

Get your MongoDB database connection information.

Select the tab for your deployment type for instructions on how to get your connection information:

  1. Go to your Atlas dedicated cluster or federated database instance for your project.

  2. Click Connect.

  3. Select the Atlas SQL Interface option.

  4. Select the Tableau Connector option under the Select your driver dropdown.

  5. Select Tableau from the dropdown.

  6. Select the database you want to connect to from the Database dropdown.

  7. Copy your connection string and connection parameters.

    Use this information to connect with Tableau in a later step.

Use a connection string that is compatible with the MongoDB Java driver. To learn more, see Connection URI.

3

Open Tableau Desktop or Tableau Server.

4

Go to the Connect menu.

5

Select MongoDB SQL Interface by MongoDB.

A connection modal displays.

6

Enter your database connection information:

Enter your SQL Interface connection string you saved in a previous step.

7

Select your authentication method.

Choose your Authentication Mechanism from the dropdown.

For information about all supported authentication mechanisms, see SQL Interface Authentication.

  • Username: Enter your MongoDB username.

  • Password: Enter your MongoDB password.

Configure your PEM certificate using one of the following methods:

  • Use a PEM File Path:

    In your mongodb_jdbc.properties file, set the x509pempath property to your PEM file's path. For example, x509pempath=/certs/client-cert.pem.

    • If your PEM file is unencrypted, do not select Provide PEM Contents. No further action is required.

    • If your PEM file is encrypted, select Provide PEM Contents and enter the file's passphrase in the Password field.

  • Provide PEM Contents:

    Select the checkbox next to Provide PEM Contents and enter your certificate data into the Password field:

    • Unencrypted Content: Paste the full certificate content directly into the field.

    • Encrypted Content: Paste a JSON object containing the content and passphrase:

      { "pem": "<PEM-CONTENT>", "passphrase": "<PEM-PASSPHRASE>" }

Enter the Kerberos principal name in the Username field. For example, user@EXAMPLE.COM.

No additional properties or fields are required in the connection dialog for OIDC.

8

Click Sign In.

Configure Tableau Logging

To change the logging configuration for the MongoDB JDBC driver, add logging properties to the mongodb_jdbc.properties file. The location of this file depends on your platform:

Platform
Path

macOS

~/Documents/My Tableau Repository/Datasources/mongodb_jdbc.properties
~/Documents/My Tableau Prep Repository/Datasources/mongodb_jdbc.properties

Windows

C:\Users\<username>\Documents\My Tableau Repository\Datasources\mongodb_jdbc.properties
C:\Users\<username>\Documents\My Tableau Prep Repository\Datasources\mongodb_jdbc.properties

Tableau Server (RHEL)

/var/opt/tableau/tableau_server/data/tabsvc/vizqlserver/Datasources/mongodb_jdbc.properties

Copy this file to all server nodes.

To configure logging, add the following properties to the file:

loglevel=INFO
logdir=<path-to-log-directory>

The loglevel property sets the verbosity of the driver logs. It accepts the following values, in order of increasing verbosity: OFF, SEVERE, WARNING, INFO, FINE, and FINER. The default is OFF.

The logdir property sets the directory where the driver writes log files. The directory must already exist. If you omit logdir or set it to console, the driver writes logs to the console instead of to a file.

Important

In production environments, start with the SEVERE log level. Raise the level only when you must diagnose an issue, because each level adds a large amount of output. At the FINER level, the driver logs every call that retrieves data for each cell of each result set.

To learn more about properties files in Tableau, see the Tableau documentation.

Connect Power BI

Connect an Atlas dedicated cluster, an Atlas federated database instance, or a self-hosted Enterprise Advanced (EA) database to Power BI using the Power BI Connector for MongoDB.

Prerequisites

  • The MongoDB ODBC driver. To install, see SQL Interface Driver Setup. To use Direct Query, you must install version 1.2 or later.

  • Power BI Desktop 64 bit. Microsoft updates and releases Power BI monthly, and Atlas supports only the latest version of Power BI Desktop.

  • Windows operating system. To learn the Windows OS versions that Power BI Desktop supports, see the Microsoft documentation.

Procedure

The following steps show you how to connect to MongoDB with Power BI:

1

Download the Power BI Connector for MongoDB.

  1. Download the latest Power BI Connector pqx file from the MongoDB download center.

    Note

    The Power BI Connector for MongoDB ships with Power BI Desktop. If your version of Power BI Desktop already has the MongoDB Atlas SQL connector, skip this step. To use a different version than the one bundled with Power BI Desktop, complete this step.

  2. Move the connector file to the following directory path:

    C:\Users\<user>\Documents\Power BI Desktop\Custom Connectors.

    Create this folder if it doesn't already exist.

2

Get your MongoDB database connection information.

Select the tab for your deployment type for instructions on how to get your connection information:

  1. Go to your Atlas dedicated cluster or federated database instance for your project.

  2. Click the Connect button.

  3. Select the Atlas SQL Interface option.

  4. Select the Power BI Connector option under the Select your driver dropdown.

  5. Copy your connection string.

    Use this information to connect with Power BI in a later step.

Use your MongoDB deployment URI. To learn more, see Connection Strings.

3

Connect from Power BI Desktop.

  1. Open Power BI Desktop.

  2. Select Get data from the Home menu.

  3. Find and select the MongoDB Atlas SQL connector.

    1. Type mongo in the search bar to find the new connector.

    2. Select MongoDB Atlas SQL.

    3. Click Connect.

  4. Enter the URI and the database name and click OK.

    The MongoDB URI is the connection string that you copied in a previous step.

    In the Native query field, you can optionally enter a SQL query. Power BI uses the SQL query as the direct source for the data. You can also add or change the SQL query in the Power Query editor after you connect.

  5. Enter your Atlas User name and Password and click Connect.

    By default, users can access all namespaces that their roles and connection URI permit. If you use custom roles to restrict access, you can grant users access to additional namespaces in the Edit User menu. To learn more, see Configure Database Users.

    For information about other supported authentication mechanisms, see SQL Interface Authentication.

Direct Query

Direct Query is a connection mode available with the Power BI Connector for MongoDB version 1.2 and later. To use Direct Query, you must install MongoDB ODBC Driver version 1.2 or later. You don't need to configure a DSN.

Direct Query is an alternative to the standard Import Mode, and allows you to query your database directly. This guarantees up-to-date data but may take longer to return results.

Direct Query does not support some actions. If you try to perform an unsupported action, Power BI prompts you to switch to Import Mode.

Connect DBeaver

Connect your Atlas dedicated cluster, Atlas federated database instance, or self-managed Enterprise Advanced (EA) deployment to DBeaver using the MongoDB JDBC Driver.

Prerequisites

Procedure

To connect from DBeaver:

1

Get your MongoDB database connection information.

Select the tab for your deployment type for instructions on how to get your connection information:

  1. Go to your Atlas dedicated cluster or federated database instance for your project.

  2. Click the Connect button.

  3. Select the Atlas SQL Interface option.

  4. Select the JDBC Driver option under the Select your driver dropdown.

  5. Select the database you want to connect to from the Database dropdown.

  6. Copy your connection string.

    Use this information to connect with DBeaver in a later step.

Use a connection string that is compatible with the MongoDB Java driver. To learn more, see Connection URI.

2

Open your DBeaver application.

3

Add a driver to DBeaver.

  1. In DBeaver, click Database and select Driver Manager from the dropdown menu.

  2. Click New to open the Create new driver modal.

  3. In the Settings tab, specify the following information:

    Driver Name

    MongoSQL

    Class Name

    com.mongodb.jdbc.MongoDriver

  4. In the Libraries tab, click Add File and add your JDBC driver all.jar file.

    Click Find Class.

  5. Click OK. The Create new driver modal closes.

4

Create a database connection.

  1. In DBeaver, click Database and select New Database Connection from the dropdown menu to open the Connect to a database modal.

  2. From the list of databases, select the MongoDB database driver that you created in the previous step.

    If you don't see MongoDB, select the All category inside the modal.

    Click Next.

  3. In the Main tab, enter the following information:

    JDBC URL

    Connection string obtained from a previous step.

    Username

    MongoDB user authorized for the connection.

    Password

    Password associated with the MongoDB user.

  4. In the Driver properties tab, expand User Properties. Add the following key-value properties:

    database

    The name of your virtual database.

    user

    The MongoDB user to connect with. Not required if you entered a Username in the previous step.

Next Steps

After you connect your SQL tool to your MongoDB database, you can query your data. To learn more, see:

Note

To connect using a private endpoint, see Connect to the MongoDB SQL Interface with a Private Endpoint.

Back
Driver Setup
Next
Query
Rate this page

On this page